import {Layout} from '../../src/Layout';
import {PendingBadge} from '../../src/PendingBadge';
import {InstallCommand} from '../../src/InstallCommand';
import {StaticTable} from '../../src/StaticTable';
export default Layout;

export const section = 'Guides';
export const tags = ['codemod', 'upgrade', 'update'];
export const description = 'How to migrate from React Spectrum v3 to Spectrum 2.';

# Migrating to Spectrum 2

<PageDescription>Learn how to migrate from React Spectrum v3 to Spectrum 2.</PageDescription>

An automated upgrade assistant is available by running the following command in the project you want to upgrade:

<InstallCommand isCommand pkg="@react-spectrum/codemods" flags="s1-to-s2" />

To only upgrade specific components, provide a `--components` argument with a comma-separated list of components to upgrade:

<InstallCommand isCommand pkg="@react-spectrum/codemods" flags="s1-to-s2 --components=Button,TextField" />

The following arguments are also available:

- `--path` - Path to apply the upgrade changes to. Defaults to the current directory (`.`)
- `--dry` - Runs the upgrade assistant without making changes to components
- `--ignore-pattern` - Ignore files that match the provided glob expression. Defaults to `'**/node_modules/**'`

For cases that the upgrade assistant doesn't handle automatically or where you'd rather upgrade some components manually, use the guide below.

Note that <PendingBadge /> indicates that future changes are expected, and the current solution should be considered temporary.

## Components

### All components

- Update imports to use the `@react-spectrum/s2` package instead of `@adobe/react-spectrum` or individual packages like `@react-spectrum/button`
- Update [style props](v3/styling#style-props) to use the style macro instead. See the 'Style props' section below

### Accordion

- Update `Item` to be `Disclosure`. `Disclosure` should now consist of two children: `DisclosureTitle` and `DisclosurePanel`. Note that you can now add interactive elements inside the header and adjacent to the title by using the `DisclosureHeader` component with the `DisclosureTitle` and interactive elements inside.
- Update `Item`'s title prop to be a child of `DisclosureTitle`
- Update children of `Item` to be children of `DisclosurePanel`
- Update `key` to be `id` (and keep `key` if rendered inside `array.map`)
- Remove `disabledKeys` and add `isDisabled` to individual `Disclosure` components
- Add `allowsMultipleExpanded` to allow multiple `Disclosure` components to be expanded at once (previously default behavior)

### ActionBar

- Remove `ActionBarContainer` and move `ActionBar` to `renderActionBar` prop of `TableView` or `CardView`
- Update `Item` to `ActionButton`
- Update root level `onAction` to be called via `onPress` on each `ActionButton`
- Apply `isDisabled` directly on each `ActionButton` or `ToggleButton` instead of root level `disabledKeys`
- Update `key` to be `id` (and keep `key` if rendered inside `array.map`)
- Convert dynamic collections render function to `items.map`
- <PendingBadge /> Comment out `buttonLabelBehavior` (it has not been implemented yet)

### ActionButton

No updates needed.

### ActionMenu

- <PendingBadge /> Comment out `closeOnSelect` (it has not been implemented yet)
- <PendingBadge /> Comment out `trigger` (it has not been implemented yet)
- Update `Item` to be a `MenuItem`

### ActionGroup

- Use `ActionButtonGroup` if you are migrating from an `ActionGroup` that didn't allow for selection. `ActionButtonGroup` takes `ActionButtons` as children.
- Use `ToggleButtonGroup` if you are migrating from an `ActionGroup` that used single or multiple selection. `ToggleButtonGroup` takes `ToggleButtons` as children.
- <PendingBadge /> Comment out `overflowMode` (it has not been implemented yet)
- <PendingBadge /> Comment out `buttonLabelBehavior` (it has not been implemented yet)
- <PendingBadge /> Comment out `summaryIcon` (it has not been implemented yet)
- Update root level `onAction` to called via `onPress` on each `ActionButton`
- Apply `isDisabled` directly on each `ActionButton` or `ToggleButton` instead of root level `disabledKeys`
- Update `key` to be `id` (and keep `key` if rendered inside `array.map`)
- Convert dynamic collections render function to `items.map`

### AlertDialog

No updates needed.

### Avatar

- <PendingBadge /> Comment out `isDisabled` (it has not been implemented yet)
- Update `size` to be a pixel value if it currently matches `'avatar-size-*'`

### Badge

- Change `variant="info"` to `variant="informative"`

### Breadcrumbs

- <PendingBadge /> Comment out `showRoot` (it has not been implemented yet)
- <PendingBadge /> Comment out `isMultiline` (it has not been implemented yet)
- <PendingBadge /> Comment out `autoFocusCurrent` (it has not been implemented yet)
- Remove `size="S"` (Small is no longer a supported size in Spectrum 2)
- Update `Item` to be a `Breadcrumb`

### Button

- Change `variant="cta"` to `variant="accent"`
- Change `variant="overBackground"` to `variant="primary" staticColor="white"`
- Change `style` to `fillStyle`
- Remove `isQuiet` (it is no longer supported in Spectrum 2)
- If `href` is present, the `Button` should be converted to a `LinkButton`
- Remove `elementType` (it is no longer supported in Spectrum 2)

### ButtonGroup

No updates needed.

### Calendar

No updates needed.

### Checkbox

No updates needed.

### CheckboxGroup

- Remove `showErrorIcon` (it has been removed due to accessibility issues)

### ColorArea

- Remove `size` and instead provide a size via the style macro (i.e. `styles={style({size: 20})}`)

### ColorField

- Remove `isQuiet` (it is no longer supported in Spectrum 2)
- Change `validationState="invalid"` to `isInvalid`
- Remove `validationState="valid"` (it is no longer supported in Spectrum 2)

### ColorSlider

- Remove `showValueLabel` (it has been removed due to accessibility issues)

### ColorSwatch

No updates needed.

### ColorWheel

- Remove `size` and instead provide a size via the style macro (i.e. `styles={style({size: 20})}`)

### ComboBox

- Change `menuWidth` value from a `DimensionValue` to a pixel value
- Remove `isQuiet` (it is no longer supported in Spectrum 2)
- Change `validationState="invalid"` to `isInvalid`
- Remove `validationState="valid"` (it is no longer supported in Spectrum 2)
- Update `Item` to be a `ComboBoxItem`

### DateField

- Remove `isQuiet` (it is no longer supported in Spectrum 2)
- Change `validationState="invalid"` to `isInvalid`
- Remove `validationState="valid"` (it is no longer supported in Spectrum 2)

### DatePicker

- Remove `isQuiet` (it is no longer supported in Spectrum 2)
- Change `validationState="invalid"` to `isInvalid`
- Remove `validationState="valid"` (it is no longer supported in Spectrum 2)

### DateRangePicker

- Remove `isQuiet` (it is no longer supported in Spectrum 2)
- Change `validationState="invalid"` to `isInvalid`
- Remove `validationState="valid"` (it is no longer supported in Spectrum 2)

### Dialog

- Update children to move render props from being the second child of `DialogTrigger` to being a child of `Dialog`
- Remove `onDismiss` and use `onOpenChange` on the `DialogTrigger`, or `onDismiss` on the `DialogContainer` instead
- `Dialog` is now meant specifically for rendering modal dialogs only and follows the same preset layout as before
- If you are trying to create a dialog with a custom layout use `CustomDialog`
- If you are trying to create a fullscreen dialog use `FullscreenDialog`
- If you are trying to create a popover dialog use `Popover`
- Supports `isKeyboardDismissDisabled` in place of `DialogTrigger`
- Supports `isDismissible` in place of `DialogTrigger`. Note the fixed spelling from previous `isDismissible` prop.
- Supports `role: "dialog" | "alertdialog"`

### DialogContainer

- Remove `type`, this is dependent on the dialog level child that you use (e.g. `Dialog`, `FullscreenDialog`, `Popover`)
- Remove `isDismissable`, prop now exists on the dialog level component as `isDismissible`
- Remove `isKeyboardDismissDisabled`, prop now exists on the dialog level component

### DialogTrigger

- <PendingBadge /> Comment out `type="tray"` (`Tray` has not been implemented yet)
- <PendingBadge /> Comment out `mobileType` (`Tray` and other types have not been implemented yet for `Popover`)
- Remove `targetRef` (it is no longer supported in Spectrum 2)
- Update `children` to remove render props usage, and note that the `close` function was moved from `DialogTrigger` to `Dialog`
- Remove `containerPadding`, prop now exists on the `Popover` component
- Remove `crossOffset`, prop now exists on the `Popover` component
- Remove `hideArrow`, prop now exists on the `Popover` component
- Remove `isDismissable`, prop now exists on the dialog level component as `isDismissible`
- Remove `isKeyboardDismissDisabled`, prop now exists on the dialog level component
- Remove `offset`, prop now exists on the `Popover` component
- Remove `placement`, prop now exists on the `Popover` component
- Remove `shouldFlip`, prop now exists on the `Popover` component
- Remove `type`, this is dependent on the dialog level child that you use (e.g. `Dialog`, `FullscreenDialog`, `Popover`)

### Divider

- Remove Divider component if within a Dialog (Updated design for Dialog in Spectrum 2)

### Flex

- Update `Flex` to be a `div` and apply flex styles using the style macro (i.e. `<div className={style({display: 'flex'})} />`)

### Form

- Remove `isQuiet` (it is no longer supported in Spectrum 2)
- Remove `isReadOnly` (it is no longer supported in Spectrum 2)
- Remove `validationState` (it is no longer supported in Spectrum 2)
- Remove `validationBehavior` (it is no longer supported in Spectrum 2)

### Grid

- Update `Grid` to be a `div` and apply grid styles using the style macro (i.e. `<div className={style({display: 'grid'})} />`)

### IllustratedMessage

- Update illustrations to be from `@react-spectrum/s2/illustrations`. See Illustrations

### InlineAlert

- Change `variant="info"` to `variant="informative"`

### Item

- If within `Menu`: Update `Item` to be a `MenuItem`
- If within `ActionMenu`: Update `Item` to be a `MenuItem`
- If within `TagGroup`: Update `Item` to be a `Tag`
- If within `Breadcrumbs`: Update `Item` to be a `Breadcrumb`
- If within `Picker`: Update `Item` to be a `PickerItem`
- If within `ComboBox`: Update `Item` to be a `ComboBoxItem`
- If within `ListBox`: Update `Item` to be a `ListBoxItem`
- If within `TabList`: Update `Item` to be a `Tab`
- If within `TabPanels`: Update `Item` to be a `TabPanel` and remove surrounding `TabPanels`
- Update `key` to be `id` (and keep `key` if rendered inside `array.map`)

### Link

- Change `variant="overBackground"` to `staticColor="white"`
- If `a` was used inside `Link` (legacy API), remove the `a` and apply props (i.e `href`) directly to `Link`

### ListBox

- Update `Item` to be a `ListBoxItem`

### Menu

- Update `Item` to be a `MenuItem`

### MenuTrigger

- <PendingBadge /> Comment out `closeOnSelect` (it has not been implemented yet)

### NumberField

- Remove `isQuiet` (it is no longer supported in Spectrum 2)
- Change `validationState="invalid"` to `isInvalid`
- Remove `validationState="valid"` (it is no longer supported in Spectrum 2)

### Picker

- Change `menuWidth` value from a `DimensionValue` to a pixel value
- Remove `isQuiet` (it is no longer supported in Spectrum 2)
- Change `validationState="invalid"` to `isInvalid`
- Remove `validationState="valid"` (it is no longer supported in Spectrum 2)
- Update `Item` to be a `PickerItem`
- Change `isLoading` to `loadingState` and provide the appropriate loading state.
- Update `defaultSelectedKey` and `selectedKey` to be `defaultValue` and `value` respectively. See the [Picker](Picker#value) documentation for more details.

### ProgressBar

- Change `variant="overBackground"` to `staticColor="white"`
- <PendingBadge /> Comment out `labelPosition` (it has not been implemented yet)
- <PendingBadge /> Comment out `showValueLabel` (it has not been implemented yet)

### ProgressCircle

- Change `variant="overBackground"` to `staticColor="white"`

### Radio

No updates needed.

### RadioGroup

- Change `validationState="invalid"` to `isInvalid`
- Remove `validationState="valid"` (it is no longer supported in Spectrum 2)
- Remove `showErrorIcon` (it has been removed due to accessibility issues)

### RangeCalendar

No updates needed.

### RangeSlider

- Remove `showValueLabel` (it has been removed due to accessibility issues)
- <PendingBadge /> Comment out `getValueLabel` (it has not been implemented yet)
- <PendingBadge /> Comment out `orientation` (it has not been implemented yet)

### SearchField

- <PendingBadge /> Comment out icon (it has not been implemented yet)
- Remove `isQuiet` (it is no longer supported in Spectrum 2)
- Change `validationState="invalid"` to `isInvalid`
- Remove `validationState="valid"` (it is no longer supported in Spectrum 2)

### Section

- If within `Menu`: Update `Section` to be a `MenuSection`
- If within `Picker`: Update `Section` to be a `PickerSection`

### Slider

- Remove `isFilled` (Slider is always filled in Spectrum 2)
- Remove `trackGradient` (Not supported in S2 design)
- Remove `showValueLabel` (it has been removed due to accessibility issues)
- <PendingBadge /> Comment out `getValueLabel` (it has not been implemented yet)
- <PendingBadge /> Comment out `orientation` (it has not been implemented yet)

### StatusLight

- Remove `isDisabled` (it is no longer supported in Spectrum 2)
- Change `variant="info"` to `variant="informative"`

### SubmenuTrigger

No updates needed.

### Switch

No updates needed.

### TableView

- For `Column` and `Row`: Update `key` to be `id` (and keep `key` if rendered inside `array.map`)
- For dynamic tables, pass a `columns` prop into `Row`
- For `Row`: Update dynamic render function to pass in `column` instead of `columnKey`
- Move `loadingState` and `onLoadMore` from `TableBody` to `TableView`
- <PendingBadge /> Comment out `UNSTABLE_allowsExpandableRows` (it has not been implemented yet)
- <PendingBadge /> Comment out `UNSTABLE_onExpandedChange` (it has not been implemented yet)
- <PendingBadge /> Comment out `UNSTABLE_expandedKeys` (it has not been implemented yet)
- <PendingBadge /> Comment out `UNSTABLE_defaultExpandedKeys` (it has not been implemented yet)

### Tabs

- Inside `TabList`: Update `Item` to be `Tab`
- Update `items` on `Tabs` to be on `TabList`
- Inside `TabPanels`: Update `Item` to be a `TabPanel` and remove the surrounding `TabPanels`
- Remove `isEmphasized` (it is no longer supported in Spectrum 2)
- Remove `isQuiet` (it is no longer supported in Spectrum 2)

### TagGroup

- Rename `actionLabel` to `groupActionLabel`
- Rename `onAction` to `onGroupAction`
- Change `validationState="invalid"` to `isInvalid`
- Update `Item` to be `Tag`

### TextArea

- <PendingBadge /> Comment out `icon` (it has not been implemented yet)
- Remove `isQuiet` (it is no longer supported in Spectrum 2)
- Change `validationState="invalid"` to `isInvalid`
- Remove `validationState="valid"` (it is no longer supported in Spectrum 2)

### TextField

- <PendingBadge /> Comment out `icon` (it has not been implemented yet)
- Remove `isQuiet` (it is no longer supported in Spectrum 2)
- Change `validationState="invalid"` to `isInvalid`
- Remove `validationState="valid"` (it is no longer supported in Spectrum 2)

### TimeField

- Remove `isQuiet` (it is no longer supported in Spectrum 2)
- Change `validationState="invalid"` to `isInvalid`
- Remove `validationState="valid"` (it is no longer supported in Spectrum 2)

### ToggleButton

No updates needed.

### Tooltip

- Remove `variant` (it is no longer supported in Spectrum 2)
- Remove `placement` and add to the parent `TooltipTrigger` instead
- Remove `showIcon` (it is no longer supported in Spectrum 2)
- Remove `isOpen` and add to the parent `TooltipTrigger` instead

### TooltipTrigger

- Update placement prop to have one value (i.e. Update `placement="bottom left"` to be `placement="bottom"`)

### TreeView

If migrating from TreeView version 3.0.0-beta.3 or before, please do the following. Otherwise, no updates needed.

- Update content within `TreeViewItem` to be wrapped in `TreeViewContentItem`

### View

- Update `View` to be a `div` and apply styles using the style macro

### Well

Update `Well` to be a `div` and apply styles using the style macro:

```tsx
<div className={style({
  display: 'block',
  textAlign: 'start',
  padding: 16,
  minWidth: 160,
  marginTop: 4,
  borderWidth: 1,
  borderRadius: 'sm',
  borderStyle: 'solid',
  borderColor: 'transparent-black-75',
  font: 'body-sm'
})} />
```

## Style props

React Spectrum v3 supported a limited set of style props for layout and positioning using Spectrum-defined values. Usage of these should be updated to instead use the style macro.

### Border width

Affected style props: `borderWidth`, `borderStartWidth`, `borderEndWidth`, `borderTopWidth`, `borderBottomWidth`, `borderXWidth`, `borderYWidth`.

Border widths should be updated to use pixel values. Use the following mappings:

<StaticTable
  headers={[
    'Spectrum 1',
    'Spectrum 2'
  ]}
  rows={[
    ["'none'", 0],
    ["'thin'", 1],
    ["'thick'", 2],
    ["'thicker'", 4],
    ["'thickest'", "'[8px]'"]
  ]}
  codeColumns={[0, 1]}
/>

### Border radius

Affected style props: `borderRadius`, `borderTopStartRadius`, `borderTopEndRadius`, `borderBottomStartRadius`, `borderBottomEndRadius`.

Border radius values should be updated to use pixel values. Use the following mappings:

<StaticTable
  headers={[
    'Spectrum 1',
    'Spectrum 2'
  ]}
  rows={[
    ["'xsmall'", "'[1px]'"],
    ["'small'", "'sm'"],
    ["'regular'", "'default'"],
    ["'medium'", "'lg'"],
    ["'large'", "'xl'"]
  ]}
  codeColumns={[0, 1]}
/>

### Dimension values

Affected style props: `width`, `minWidth`, `maxWidth`, `height`, `minHeight`, `maxHeight`, `margin`, `marginStart`, `marginEnd`, `marginTop`, `marginBottom`, `marginX`, `marginY`, `top`, `bottom`, `left`, `right`, `start`, `end`, `flexBasis`, `gap`, `columnGap`, `rowGap`, `padding`, `paddingX`, `paddingY`, `paddingStart`, `paddingEnd`, `paddingTop`, `paddingBottom`.

Dimension values should be converted to pixel values. Use the following mappings:

<StaticTable
  headers={[
    'Spectrum 1',
    'Spectrum 2'
  ]}
  rows={[
    ["'size-0'", 0],
    ["'size-10'", 1],
    ["'size-25'", 2],
    ["'size-40'", 3],
    ["'size-50'", 4],
    ["'size-65'", 5],
    ["'size-75'", 6],
    ["'size-85'", 7],
    ["'size-100'", 8],
    ["'size-115'", 9],
    ["'size-125'", 10],
    ["'size-130'", 11],
    ["'size-150'", 12],
    ["'size-160'", 13],
    ["'size-175'", 14],
    ["'size-200'", 16],
    ["'size-225'", 18],
    ["'size-250'", 20],
    ["'size-275'", 22],
    ["'size-300'", 24],
    ["'size-325'", 26],
    ["'size-350'", 28],
    ["'size-400'", 32],
    ["'size-450'", 36],
    ["'size-500'", 40],
    ["'size-550'", 44],
    ["'size-600'", 48],
    ["'size-675'", 54],
    ["'size-700'", 56],
    ["'size-800'", 64],
    ["'size-900'", 72],
    ["'size-1000'", 80],
    ["'size-1200'", 96],
    ["'size-1250'", 100],
    ["'size-1600'", 128],
    ["'size-1700'", 136],
    ["'size-2000'", 160],
    ["'size-2400'", 192],
    ["'size-3000'", 240],
    ["'size-3400'", 272],
    ["'size-3600'", 288],
    ["'size-4600'", 368],
    ["'size-5000'", 400],
    ["'size-6000'", 480],
    ["'static-size-0'", 0],
    ["'static-size-10'", 1],
    ["'static-size-25'", 2],
    ["'static-size-40'", 3],
    ["'static-size-50'", 4],
    ["'static-size-65'", 5],
    ["'static-size-100'", 8],
    ["'static-size-115'", 9],
    ["'static-size-125'", 10],
    ["'static-size-130'", 11],
    ["'static-size-150'", 12],
    ["'static-size-160'", 13],
    ["'static-size-175'", 14],
    ["'static-size-200'", 16],
    ["'static-size-225'", 18],
    ["'static-size-250'", 20],
    ["'static-size-300'", 24],
    ["'static-size-400'", 32],
    ["'static-size-450'", 36],
    ["'static-size-500'", 40],
    ["'static-size-550'", 44],
    ["'static-size-600'", 48],
    ["'static-size-700'", 56],
    ["'static-size-800'", 64],
    ["'static-size-900'", 72],
    ["'static-size-1000'", 80],
    ["'static-size-1200'", 96],
    ["'static-size-1700'", 136],
    ["'static-size-2400'", 192],
    ["'static-size-2600'", 208],
    ["'static-size-3400'", 272],
    ["'static-size-3600'", 288],
    ["'static-size-4600'", 368],
    ["'static-size-5000'", 400],
    ["'static-size-6000'", 480],
    ["'single-line-height'", 32],
    ["'single-line-width'", 192]
  ]}
  codeColumns={[0, 1]}
/>

### Break points

Break points previously used in style props can be used in the style macro with updated keys. Use the following mappings:

<StaticTable
  headers={[
    'Spectrum 1',
    'Spectrum 2'
  ]}
  rows={[
    ['base', 'default'],
    ['S', 'sm'],
    ['M', 'md'],
    ['L', 'lg']
  ]}
  codeColumns={[0, 1]}
/>
